Repository navigation
feat: Add references page to handbook - #2073
jstoobysmith wants to merge 1 commit into
Conversation
|
Thank you for this pull-request (PR). If this is your first PR, welcome to the community! While you wait for a review, note that you can review PRs too; reviewing is not restricted to maintainers. Our review guidelines explain what to look for. Over time, contributions such as reviews, maintenance and documentation are recorded on contributions.physlib.io. Three main points:
|
|
|
||
| ## 3. Include exact quotes | ||
|
|
||
| Where possible, include an exact quote from the source in the references section. Quotes can be checked in both directions: a reader can check that the quote describes the physics being formalized, and that the quote actually appears in the source. Quotes can be left out when citing an overview article. |
There was a problem hiding this comment.
I'm not so sure about this, there are often subtle differences between the informal statement and the formalisation, and also building up an API may not necessary have a headline statement that this may be applicable
|
|
||
| ## 5. Link to the exact page | ||
|
|
||
| When you cite a specific part of a paper, the link in the references section should go to the page where that part appears. On arXiv, for example, you can link directly to a given page of a paper. |
There was a problem hiding this comment.
in relation to the comment on point 3, I think this is already sufficient.
|
|
||
| ## 4. Prefer open-access sources | ||
|
|
||
| Prefer open-access sources, and include a link. Physlib is an open-source project, and it is very hard to check that a reference is correct if the source is closed access. This is a soft rule: at some point you will need to refer to the standard literature, such as Landau and Lifshitz. |
There was a problem hiding this comment.
this is not wrong, but this may give the wrong impression that formalisation has to follow a source faithfully, but in practice it might be actually desirable to come up with a better generalisation/implementation which could take inspiration from more than one source, or even a novel framework, and I think we should encourage creativity (given the contributor knows what they're doing of course).
Added a references page to the contribution handbook made with the help of AI, but all of the ideas were my own, and this is basically a transcription of those.